HAL USART I/O operations migration

This section provides information about the HAL USART I/O operations migration.

Important

The main difference between HAL1 and HAL2 in all transmit and receive functions (polling, interrupt, or DMA) is the way buffer size is specified. HAL1 uses Size for the number of data elements (u8 or u16), while HAL2 uses Size_byte to specify the buffer size in bytes, allowing more precise control.

Process Polling

Function

HAL1 / HAL2

Transmit 

HAL1:  HAL_USART_Transmit(USART_HandleTypeDef *husart, const uint8_t *pData, uint16_t Size, uint32_t Timeout)
HAL2:  HAL_USART_Transmit(hal_usart_handle_t *husart,  const void *p_data,   uint32_t size_byte, uint32_t timeout_ms)

Receive 

HAL1:  HAL_USART_Receive(USART_HandleTypeDef *husart, uint8_t *pData, uint16_t Size, uint32_t Timeout)
HAL2:  HAL_USART_Receive(hal_usart_handle_t *husart, void *p_data, uint32_t size_byte, uint32_t timeout_ms)

Transmit/Receive 

HAL1:   HAL_USART_TransmitReceive(USART_HandleTypeDef *husart, const uint8_t *pTxData, uint8_t *pRxData,
                                                                    uint16_t Size, uint32_t Timeout)
HAL2:   HAL_USART_TransmitReceive(hal_usart_handle_t *husart, const void *p_tx_data, void *p_rx_data,
                                                       uint32_t size_byte, uint32_t timeout_ms)

Related use cases: Use case: USART communication in polling mode

Process IT

Function

HAL1 / HAL2

Transmit IT 

HAL1:  HAL_USART_Transmit_IT(USART_HandleTypeDef *husart, const uint8_t *pData, uint16_t Size)
HAL2:  HAL_USART_Transmit_IT(hal_usart_handle_t *husart, const void *p_data,   uint32_t size_byte)

Receive IT 

HAL1:  HAL_USART_Receive_IT(USART_HandleTypeDef *husart, uint8_t *pData, uint16_t Size)
HAL2:  HAL_USART_Receive_IT(hal_usart_handle_t *husart, void *p_data,   uint32_t size_byte)

Transmit/Receive IT 

HAL1:  HAL_USART_TransmitReceive_IT(USART_HandleTypeDef *husart, const uint8_t *pTxData,
                                                     uint8_t *pRxData, uint16_t Size)

HAL2:  HAL_USART_TransmitReceive_IT(hal_usart_handle_t *husart, const void *p_tx_data,
                                                      void *p_rx_data, uint32_t size_byte)

Related use cases: Use case: USART TX in interrupt mode, Use case: USART RX in interrupt mode and Use case: USART RX in interrupt mode

Process DMA

Function

HAL1 / HAL2

Transmit DMA 

HAL1:  HAL_USART_Transmit_DMA(USART_HandleTypeDef *husart, const uint8_t *pData, uint16_t Size)
HAL2:  HAL_USART_Transmit_DMA(hal_usart_handle_t *husart, const void *p_data,   uint32_t size_byte)

Receive DMA 

HAL1:  HAL_USART_Receive_DMA(USART_HandleTypeDef *husart, uint8_t *pData, uint16_t Size)
HAL2:  HAL_USART_Receive_DMA(hal_usart_handle_t *husart, void *p_data,   uint32_t size_byte)

Transmit/Receive DMA 

HAL1:  HAL_USART_TransmitReceive_DMA(USART_HandleTypeDef *husart, const uint8_t *pTxData, uint8_t *pRxData,
                                                      uint16_t Size)
HAL2:  HAL_USART_TransmitReceive_DMA(hal_usart_handle_t *husart, const void *p_tx_data, void *p_rx_data,
                                                      uint32_t size_byte)

Pause DMA 

HAL1:  HAL_USART_DMAPause(USART_HandleTypeDef *husart)
HAL2:  HAL_USART_Pause_DMA(hal_usart_handle_t *husart)

Resume DMA 

HAL1:  HAL_USART_DMAResume(USART_HandleTypeDef *husart)
HAL2:  HAL_USART_Resume_DMA(hal_usart_handle_t *husart)

Related use cases: Use case: USART TX in DMA mode and Use case: USART RX in DMA mode

DMA Stop

HAL1

HAL2 

HAL_USART_DMAStop(USART_HandleTypeDef *husart)

Removed in HAL2

This function’s functionality is already covered by HAL_UART_Abort_IT().

Transfer Abort

Function

HAL1 / HAL2

Abort 

HAL1:  HAL_USART_Abort(USART_HandleTypeDef *husart)
HAL2:  HAL_USART_Abort(hal_usart_handle_t *husart)

Abort IT 

HAL1:  HAL_USART_Abort_IT(USART_HandleTypeDef *husart)
HAL2:  HAL_USART_Abort_IT(hal_usart_handle_t *husart)

IRQ Handler

Function

HAL1 / HAL2

IRQ Handler 

HAL1:  HAL_USART_IRQHandler(USART_HandleTypeDef *husart)
HAL2:  HAL_USART_IRQHandler(hal_usart_handle_t *husart)

Register Callbacks

HAL1

HAL2

In HAL1, the function HAL_USART_RegisterCallback is used to register various USART callbacks using a single function with a specific callback ID.

In HAL2, separate functions are available to register each specific USART callback, providing more granularity and control over the callback registration process. 

// Register Tx Half Complete Callback
HAL_USART_RegisterCallback(&husart,
                           HAL_USART_TX_HALFCOMPLETE_CB_ID,
                           TxHalfTransferCpltCallback);

// Register Tx Complete Callback
HAL_USART_RegisterCallback(&husart,
                           HAL_USART_TX_COMPLETE_CB_ID,
                           TxTransferCpltCallback);

// Register Rx Half Complete Callback
HAL_USART_RegisterCallback(&husart,
                           HAL_USART_RX_HALFCOMPLETE_CB_ID,
                           RxHalfTransferCpltCallback);

// Register Rx Complete Callback
HAL_USART_RegisterCallback(&husart,
                           HAL_USART_RX_COMPLETE_CB_ID,
                           RxTransferCpltCallback);

// Register Error Callback
HAL_USART_RegisterCallback(&husart,
                           HAL_USART_ERROR_CB_ID,
                           ErrorCallback);

// Register Abort Complete Callback
HAL_USART_RegisterCallback(&husart,
                           HAL_USART_ABORT_COMPLETE_CB_ID,
                           AbortCpltCallback);

// Register Rx FIFO Full Callback
HAL_USART_RegisterCallback(&husart,
                           HAL_USART_RX_FIFO_FULL_CB_ID,
                           RxFifoFullCallback);

// Register Tx FIFO Empty Callback
HAL_USART_RegisterCallback(&husart,
                           HAL_USART_TX_FIFO_EMPTY_CB_ID,
                           TxFifoEmptyCallback);

// Register Tx Half Complete Callback
HAL_USART_RegisterTxHalfCpltCallback(&husart, TxHalfTransferCpltCallback);



// Register Tx Complete Callback
HAL_USART_RegisterTxCpltCallback(&husart, TxTransferCpltCallback);



// Register Rx Half Complete Callback
HAL_USART_RegisterRxHalfCpltCallback(&husart, RxHalfTransferCpltCallback);



// Register Rx Complete Callback
HAL_USART_RegisterRxCpltCallback(&husart, RxTransferCpltCallback);



// Register Error Callback
HAL_USART_RegisterErrorCallback(&husart, ErrorCallback);



// Register Abort Complete Callback
HAL_USART_RegisterAbortCpltCallback(&husart, AbortCpltCallback);




// Register Rx FIFO Full Callback
HAL_USART_RegisterRxFifoFullCallback(&husart, RxFifoFullCallback);




// Register Tx FIFO Empty Callback
HAL_USART_RegisterTxFifoEmptyCallback(&husart, TxFifoEmptyCallback);

Related concepts: Individual callback registration APIs replace global register and unregister functions

UnRegister Callbacks

In HAL2, the unregister callback API has been removed. Instead, users can manage callbacks by re-registering the default HAL USART weak callbacks as needed.

HAL1

HAL2 

// Unregister Tx Half Complete Callback
HAL_USART_UnRegisterCallback(&usart_handle,
                             HAL_USART_TX_HALFCOMPLETE_CB_ID);

// Unregister Tx Complete Callback
HAL_USART_UnRegisterCallback(&usart_handle,
                             HAL_USART_TX_COMPLETE_CB_ID);

// Unregister Rx Half Complete Callback
HAL_USART_UnRegisterCallback(&usart_handle,
                             HAL_USART_RX_HALFCOMPLETE_CB_ID);

// Unregister Rx Complete Callback
HAL_USART_UnRegisterCallback(&usart_handle,
                             HAL_USART_RX_COMPLETE_CB_ID);

// Unregister Error Callback
HAL_USART_UnRegisterCallback(&usart_handle,
                             HAL_USART_ERROR_CB_ID);

// Unregister Abort Complete Callback
HAL_USART_UnRegisterCallback(&usart_handle,
                             HAL_USART_ABORT_COMPLETE_CB_ID);

// Unregister Rx FIFO Full Callback
HAL_USART_UnRegisterCallback(&usart_handle,
                             HAL_USART_RX_FIFO_FULL_CB_ID);

// Unregister Tx FIFO Empty Callback
HAL_USART_UnRegisterCallback(&usart_handle,
                             HAL_USART_TX_FIFO_EMPTY_CB_ID);

// Re-register default Tx Half Complete Callback
HAL_USART_RegisterTxHalfCpltCallback(&usart_handle,
                                     HAL_USART_TxHalfCpltCallback);

// Re-register default Tx Complete Callback
HAL_USART_RegisterTxCpltCallback(&usart_handle,
                                 HAL_USART_TxCpltCallback);

// Re-register default Rx Half Complete Callback
HAL_USART_RegisterRxHalfCpltCallback(&usart_handle,
                                     HAL_USART_RxHalfCpltCallback);

// Re-register default Rx Complete Callback
HAL_USART_RegisterRxCpltCallback(&usart_handle,
                                 HAL_USART_RxCpltCallback);

// Re-register default Error Callback
HAL_USART_RegisterErrorCallback(&usart_handle,
                                HAL_USART_ErrorCallback);

// Re-register default Abort Complete Callback
HAL_USART_RegisterAbortCpltCallback(&usart_handle,
                                    HAL_USART_AbortCpltCallback);

// Re-register default Rx FIFO Full Callback
HAL_USART_RegisterRxFifoFullCallback(&usart_handle,
                                     HAL_USART_RxFifoFullCallback);

// Re-register default Tx FIFO Empty Callback
HAL_USART_RegisterTxFifoEmptyCallback(&usart_handle,
                                      HAL_USART_TxFifoEmptyCallback);

Related concepts: Individual callback registration APIs replace global register and unregister functions

Default Callbacks

Function

HAL1 / HAL2

TX Half Complete Callback 

HAL1:  HAL_USART_TxHalfCpltCallback(USART_HandleTypeDef *husart)
HAL2:  HAL_USART_TxHalfCpltCallback(hal_usart_handle_t *husart)

TX Complete Callback 

HAL1:  HAL_USART_TxCpltCallback(USART_HandleTypeDef *husart)
HAL2:  HAL_USART_TxCpltCallback(hal_usart_handle_t *husart)

RX Half Complete Callback 

HAL1:  HAL_USART_RxHalfCpltCallback(USART_HandleTypeDef *husart)
HAL2:  HAL_USART_RxHalfCpltCallback(hal_usart_handle_t *husart)

RX Complete Callback 

HAL1:  HAL_USART_RxCpltCallback(USART_HandleTypeDef *husart)
HAL2:  HAL_USART_RxCpltCallback(hal_usart_handle_t *husart)

TX RX Complete Callback 

HAL1:  HAL_USART_TxRxCpltCallback(USART_HandleTypeDef *husart)
HAL2:  HAL_USART_TxRxCpltCallback(hal_usart_handle_t *husart)

Error Callback 

HAL1:  HAL_USART_ErrorCallback(USART_HandleTypeDef *husart)
HAL2:  HAL_USART_ErrorCallback(hal_usart_handle_t *husart)

Abort Complete Callback 

HAL1:  HAL_USART_AbortCpltCallback(USART_HandleTypeDef *husart)
HAL2:  HAL_USART_AbortCpltCallback(hal_usart_handle_t *husart)

RX FIFO Full Callback 

HAL1:  HAL_USARTEx_RxFifoFullCallback(USART_HandleTypeDef *husart)
HAL2:  HAL_USART_RxFifoFullCallback(hal_usart_handle_t *husart)

TX FIFO Empty Callback 

HAL1:  HAL_USARTEx_TxFifoEmptyCallback(USART_HandleTypeDef *husart)
HAL2:  HAL_USART_TxFifoEmptyCallback(hal_usart_handle_t *husart)